The Companion Button Controller (attached to Gameboard) exposes all the companion button features available to creators.

The Gameboard node is always available in your game as long as the SDK has been integrated. In order to access it we just need to find it.

    var gameboard = GetNode("/root/GameboardSDK") as GameboardPlugin;

With access to our Gameboard object we can then move on to obtain a reference to the Companion Buttons Controller. This is the controller that handles all the functions related to companion buttons.

NOTE: Right now, some of the button actions are tied to Cards. For example, buttons set with SetCompanionButtonValues will be tied to the CardController's CardButtonPressed event. Buttons set in the Dialog are tied to the CompanionButtonPressed event. There are plans to refactor this in future versions.

We will first need to define a reference to the controller to make it available throughout our script:

     ButtonController companionButtonController;
     CardController cardController;

With our reference defined, we can now proceed to listen for button events. In our case well have a function called OnStandardButtonPressed handle this events.

     companionButtonController = gameboard.GetNode("ButtonController") as ButtonController;
     cardController = gameboard.GetNode("CardController") as CardController;

     companionButtonController.CompanionButtonPressed += OnStandardButtonPressed;
     cardController.CardButtonPressed += OnCardButtonPressed;

Now that we are able to receive the button press events all that remains is to handle them in the game.

    void OnStandardButtonPressed(GameboardCompanionButtonPressedEventArgs companionButtonEvent)
    {
        // Handle pressed event of the Standard button on Companion. (Dialog buttons)
    }

    void OnCardButtonPressed(GameboardCompanionCardsButtonPressedEventArgs companionButtonEvent)
    {
       // Handle pressed event of card button (Includes cardId in the event args)
    }

With the controller at hand we can now send requests to Companion to display a given button.

NOTE: Currently adding buttons in this way is only supported in the Cards view. Pressing these buttons will send a CardButtonPressed event that can be listened to from the CardController.

By default, the button is not visible on the companion app, it must be enabled with SetCompanionButtonVisiblity

Example

In this example we are creating a button that you want to appear in the middle position on "userABC"'s companion with the text "Hello World", the specified callback identifier of "HelloWorldCallback", and an optional texture defined by ID "textureId".

    // Note: These assets need to be uploaded using the Asset Controller before making this call or the button textures won't show.
    await companionButtonController.SetCompanionCardButton("userABC", "buttonId", "Hello World.", "HelloWorldCallback", "textureId", CardButtonPosition.Center);
    //Set that button visible
    await companionButtonController.SetCompanionButtonVisiblity("userABC", "buttonId", true);

Setting multiple buttons

There is a method available that allows setting and showing multiple buttons at once. You will get back an array of responses, corresponding to the response received when setting/showing each button.

CompanionMessageResponseArgs[] responses = await companionButtonController.SetAndShowMultipleCompanionCardButtons("userABC",
            new CompanionCardButton[]
                {
                    new CompanionCardButton("LeftBtnId", "LeftBtn", CardButtonPosition.Left),
                    new CompanionCardButton("CenterBtnId", "CenterBtn", CardButtonPosition.Center),
                    new CompanionCardButton("RightBtnId", "RightBtn", CardButtonPosition.Right) {
                        //Optional params
                        assetId = "textureId",
                        buttonCallback = "RightCallback",
                    },
                }
            );

Although we are working in a managed environment it is always a good idea to clean the listeners when no longer needed.

    public override void _ExitTree()
    {
        companionButtonController.CompanionButtonPressed -= OnStandardButtonPressed;
        cardController.CardButtonPressed -= OnCardButtonPressed;
    }

This section include the entire code in one single, easy to copy section.

    ButtonController companionButtonController;
    CardController cardController;

    // Called when the node enters the scene tree for the first time.
    public override void _Ready()
    {
        GameboardPlugin gameboard = GetNode("/root/GameboardSDK") as GameboardPlugin;

        companionButtonController = gameboard.GetNode("ButtonController") as ButtonController;
        cardController = gameboard.GetNode("CardController") as CardController;

        companionButtonController.CompanionButtonPressed += OnStandardButtonPressed;
        cardController.CardButtonPressed += OnCardButtonPressed;
    }

    void OnStandardButtonPressed(GameboardCompanionButtonPressedEventArgs companionButtonEvent)
    {
        // Handle pressed event of the Standard button on Companion.
    }

    void OnCardButtonPressed(GameboardCompanionCardsButtonPressedEventArgs companionButtonEvent)
    {
       // Handle pressed event of card button (Includes cardId in the event args)
    }

    public override void _ExitTree()
    {
        companionButtonController.CompanionButtonPressed -= OnStandardButtonPressed;
        cardController.CardButtonPressed -= OnCardButtonPressed;
    }